<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>

    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta content="Cask Data, Inc." name="author" />
<meta content="HTTP RESTful Interface to the Cask Data Application Platform" name="description" />
<meta content="Copyright © 2014-2017 Cask Data, Inc." name="copyright" />


    <meta name="git_release" content="6.1.1">
    <meta name="git_hash" content="05fbac36f9f7aadeb44f5728cea35136dbc243e5">
    <meta name="git_timestamp" content="2020-02-09 08:22:47 +0800">
    <title>Service HTTP RESTful API</title>

    <link rel="stylesheet" href="../_static/cdap-bootstrap.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <link rel="stylesheet" href="../_static/bootstrap-3.3.6/css/bootstrap.min.css" type="text/css" />
    <link rel="stylesheet" href="../_static/bootstrap-3.3.6/css/bootstrap-theme.min.css" type="text/css" />
    <link rel="stylesheet" href="../_static/css/bootstrap-sphinx.css" type="text/css" />
    <link rel="stylesheet" href="../_static/css/cdap-dynamicscrollspy-4.css" type="text/css" />
    <link rel="stylesheet" href="../_static/css/jquery.mCustomScrollbar.css" type="text/css" />
    <link rel="stylesheet" href="../_static/css/cdap-jquery.mCustomScrollbar.css" type="text/css" />
    <link rel="stylesheet" href="../_static/css/abixTreeList-2.css" type="text/css" />
    <link rel="stylesheet" href="../_static/cdap-bootstrap.css" type="text/css" />

    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '',
        VERSION:     '6.1.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/language_data.js"></script>

    <link rel="shortcut icon" href="../_static/favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="top" title="Cask Data Application Platform 6.1.1 Documentation" href="../index.html" />
    <link rel="up" title="CDAP HTTP RESTful API v3" href="index.html" />
    <link rel="next" title="Transaction Service HTTP RESTful API" href="transactions.html" />
    <link rel="prev" title="Security HTTP RESTful API" href="security.html" />
    <!-- block extrahead -->
    <meta charset='utf-8'>
    <meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
    <meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
    <meta name="apple-mobile-web-app-capable" content="yes">
    <!-- block extrahead end -->

</head>
<body role="document">

<!-- block navbar -->
<div id="navbar" class="navbar navbar-inverse navbar-default navbar-fixed-top">
    <div class="container-fluid">
      <div class="row">
        <div class="navbar-header">
          <!-- .btn-navbar is used as the toggle for collapsed navbar content -->
          <a class="navbar-brand" href="../table-of-contents/../../index.html">
            <span><img alt="CDAP logo" src="../_static/cdap_logo.svg"/></span>
          </a>

          <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
            <span class="icon-bar"></span>
            <span class="icon-bar"></span>
            <span class="icon-bar"></span>
          </button>

          <div class="pull-right">
            <div class="dropdown version-dropdown">
              <a href="#" class="dropdown-toggle" data-toggle="dropdown"
                role="button" aria-haspopup="true" aria-expanded="false">
                v 6.1.1 <span class="caret"></span>
              </a>
              <ul class="dropdown-menu">
                <li><a href="//docs.cdap.io/cdap/5.1.2/en/index.html">v 5.1.2</a></li>
                <li><a href="//docs.cdap.io/cdap/4.3.4/en/index.html">v 4.3.4</a></li>
              </ul>
            </div>
          </div>
          <form class="navbar-form navbar-right navbar-search" action="../search.html" method="get">
            <div class="form-group">
              <div class="navbar-search-image material-icons"></div>
              <input type="text" name="q" class="form-control" placeholder="  Search" />
            </div>
            <input type="hidden" name="check_keywords" value="yes" />
            <input type="hidden" name="area" value="default" />
          </form>

          <div class="collapse navbar-collapse nav-collapse navbar-right navbar-navigation">
            <ul class="nav navbar-nav"><li class="docsite-nav-tab-container"><a class="docsite-nav-tab-link " href="../table-of-contents/../../index.html">简介</a></li><li class="docsite-nav-tab-container"><a class="docsite-nav-tab-link " href="../table-of-contents/../../guides.html">手册</a></li><li class="docsite-nav-tab-container"><a class="docsite-nav-tab-link current" href="../table-of-contents/../../reference-manual/index.html">参考</a></li><li class="docsite-nav-tab-container"><a class="docsite-nav-tab-link " href="../table-of-contents/../../faqs/index.html">帮助</a></li>
            </ul>
          </div>

        </div>
      </div>
    </div>
  </div><!-- block navbar end -->
<!-- block main content -->
<div class="main-container container">
  <div class="row"><div class="col-md-2">
      <div id="sidebar" class="bs-sidenav scrollable-y-outside" role="complementary">
<!-- theme_manual: reference-manual -->
<!-- theme_manual_highlight: reference -->
<!-- sidebar_title_link: Reference -->

  <div role="note" aria-label="manuals links"><h3>Reference</h3>
    <ul class="reference-page-menu">
      <nav class="pagenav">
      <ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../index.html"> Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../characters.html"> Supported Characters</a></li>
<li class="toctree-l1"><a class="reference internal" href="../cli-api.html"> Command Line Interface API</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html"> HTTP RESTful API</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="introduction.html">Introduction</a></li>
<li class="toctree-l2"><a class="reference internal" href="artifact.html">Artifact</a></li>
<li class="toctree-l2"><a class="reference internal" href="configuration.html">Configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="dataset.html">Dataset</a></li>
<li class="toctree-l2"><a class="reference internal" href="lifecycle.html">Lifecycle</a></li>
<li class="toctree-l2"><a class="reference internal" href="logging.html">Logging</a></li>
<li class="toctree-l2"><a class="reference internal" href="metadata.html">Metadata</a></li>
<li class="toctree-l2"><a class="reference internal" href="metrics.html">Metrics</a></li>
<li class="toctree-l2"><a class="reference internal" href="monitor.html">Monitor</a></li>
<li class="toctree-l2"><a class="reference internal" href="namespace.html">Namespace</a></li>
<li class="toctree-l2"><a class="reference internal" href="dashboard.html">Dashboard</a></li>
<li class="toctree-l2"><a class="reference internal" href="preferences.html">Preferences</a></li>
<li class="toctree-l2"><a class="reference internal" href="profile.html">Profile</a></li>
<li class="toctree-l2"><a class="reference internal" href="query.html">Query</a></li>
<li class="toctree-l2"><a class="reference internal" href="reports.html">Reports</a></li>
<li class="toctree-l2"><a class="reference internal" href="security.html">Security</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Service</a></li>
<li class="toctree-l2"><a class="reference internal" href="transactions.html">Transactions</a></li>
<li class="toctree-l2"><a class="reference internal" href="workflow.html">Workflow</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../java-client-api.html"> Java Client API</a></li>
<li class="toctree-l1"><a class="reference internal" href="../javadocs/index.html"> Javadocs</a></li>
<li class="toctree-l1"><a class="reference internal" href="../release-notes.html"> 发行说明</a></li>
<li class="toctree-l1"><a class="reference internal" href="../licenses/index.html"> Trademarks, Licenses, and Dependencies</a></li>
<li class="toctree-l1"><a class="reference internal" href="../glossary.html"> 术语表</a></li>
<li class="toctree-l1"><a class="reference internal" href="../genindex.html"> Index</a></li>
</ul>
</nav>
    </ul>
  </div></div>
    </div><div class="col-md-8 content" id="main-content">
    
  <div class="section" id="service-http-restful-api">
<span id="http-restful-api-service"></span><h1>Service HTTP RESTful API<a class="headerlink" href="#service-http-restful-api" title="Permalink to this headline">🔗</a></h1>
<p>Use the CDAP Service HTTP RESTful API to list all services and making requests to the
methods of an application’s services. See the <a class="reference internal" href="lifecycle.html#http-restful-api-lifecycle"><span class="std std-ref">Lifecycle HTTP RESTful API</span></a> for how to
control the lifecycle of services.</p>
<p>For system services, see the <a class="reference internal" href="monitor.html#http-restful-api-monitor"><span class="std std-ref">Monitor HTTP RESTful API</span></a> and its methods.</p>
<p>Additional details and examples are found in the <a class="reference external" href="../../../developer-manual/building-blocks/services.html#user-services" title="(in Cask Data Application Platform v6.1.1)"><span class="xref std std-ref">开发手册: Services</span></a>.</p>
<p>All methods or endpoints described in this API have a base URL (typically
<code class="docutils literal notranslate"><span class="pre">http://&lt;host&gt;:11015</span></code> or <code class="docutils literal notranslate"><span class="pre">https://&lt;host&gt;:10443</span></code>) that precedes the resource
identifier, as described in the <a class="reference internal" href="introduction.html#http-restful-api-conventions-base-url"><span class="std std-ref">RESTful API Conventions</span></a>.
These methods return a status code, as listed in the <a class="reference internal" href="introduction.html#http-restful-api-status-codes"><span class="std std-ref">RESTful API  Status Codes</span></a>.</p>
<div class="section" id="listing-all-services">
<span id="http-restful-api-service-listing"></span><h2>Listing all Services<a class="headerlink" href="#listing-all-services" title="Permalink to this headline">🔗</a></h2>
<p>You can list all services in a namespace in CDAP by issuing an HTTP GET request to the URL:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/services</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
</tbody>
</table>
<p>The response body will contain a JSON-formatted list of the existing services:</p>
<div class="highlight-json-ellipsis notranslate"><div class="highlight"><pre><span></span><span class="p">[</span>
    <span class="p">{</span>
        <span class="nt">&quot;app&quot;</span><span class="p">:</span> <span class="s2">&quot;PurchaseHistory&quot;</span><span class="p">,</span>
        <span class="nt">&quot;description&quot;</span><span class="p">:</span> <span class="s2">&quot;Service to retrieve Product IDs.&quot;</span><span class="p">,</span>
        <span class="nt">&quot;id&quot;</span><span class="p">:</span> <span class="s2">&quot;CatalogLookup&quot;</span><span class="p">,</span>
        <span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;CatalogLookup&quot;</span><span class="p">,</span>
        <span class="nt">&quot;type&quot;</span><span class="p">:</span> <span class="s2">&quot;Service&quot;</span>
    <span class="p">}</span>
    <span class="c">...</span>
<span class="p">]</span>
</pre></div>
</div>
</div>
<div class="section" id="checking-service-availability">
<h2>Checking Service Availability<a class="headerlink" href="#checking-service-availability" title="Permalink to this headline">🔗</a></h2>
<p>Once a service is started, you can can check whether the service is ready to accept service method requests by issuing
an HTTP GET request to the URL:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/services/&lt;service-id&gt;/available</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">app-id</span></code></td>
<td>Name of the application</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">service-id</span></code></td>
<td>Name of the service whose availability needs to be checked</td>
</tr>
</tbody>
</table>
<p class="rubric">HTTP Responses</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Status Codes</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">503</span> <span class="pre">Service</span> <span class="pre">Unavailable</span></code></td>
<td>The service is unavailable to take requests at the moment. For example, it might not have been started, or
if the service has been started, it might not have become available yet to take requests.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">200</span> <span class="pre">OK</span></code></td>
<td>Service is ready to accept requests.</td>
</tr>
</tbody>
</table>
<p>Note that when the service availability check returns <code class="docutils literal notranslate"><span class="pre">200</span></code>, it is expected that calling the service
methods will work. However, there is still a possibility for a service method call to fail; for example, if the
service fails just after the availability call returns. It is highly recommended that error conditions
(a <code class="docutils literal notranslate"><span class="pre">503</span></code> status code) be handled when making requests to service methods simply by retrying the request.</p>
</div>
<div class="section" id="requesting-service-methods">
<h2>Requesting Service Methods<a class="headerlink" href="#requesting-service-methods" title="Permalink to this headline">🔗</a></h2>
<p>To make a request to a service’s method, send the value of the method’s <code class="docutils literal notranslate"><span class="pre">&#64;Path</span></code> annotation
as part of the request URL along with any additional headers, body, and query parameters.</p>
<p>The request type is defined by the service’s method:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">&lt;request-type&gt; /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/services/&lt;service-id&gt;/methods/&lt;endpoint-path&gt;</span>
</pre></div>
</div>
<p><strong>Note:</strong> Any reserved or unsafe characters in the path parameters should be encoded using
<a class="reference internal" href="introduction.html#http-restful-api-conventions-reserved-unsafe-characters"><span class="std std-ref">percent-encoding</span></a>. See the
section on <a class="reference external" href="../../../developer-manual/building-blocks/services.html#services-path-parameters" title="(in Cask Data Application Platform v6.1.1)"><span class="xref std std-ref">Path Parameters</span></a> for suggested approaches to
encoding parameters.</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">request-type</span></code></td>
<td>One of GET, POST, PUT, or DELETE. This is defined by the handler method.</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">app-id</span></code></td>
<td>Name of the application being called</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">service-id</span></code></td>
<td>Name of the service being called</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">endpoint-path</span></code></td>
<td>Endpoint path of the method being called</td>
</tr>
</tbody>
</table>
<p class="rubric">HTTP Responses</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Status Codes</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">503</span> <span class="pre">Service</span> <span class="pre">Unavailable</span></code></td>
<td>The service is unavailable. For example, it may not yet have been started.</td>
</tr>
</tbody>
</table>
<p>Other responses are defined by the service’s method.</p>
<p class="rubric">Example</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><th class="stub">HTTP Method</th>
<td><code class="docutils literal notranslate"><span class="pre">GET</span> <span class="pre">/v3/namespaces/default/apps/WordCount/services/RetrieveCounts/methods/count/Cask?limit=2</span></code></td>
</tr>
<tr class="row-even"><th class="stub">Description</th>
<td>Make a request to the <code class="docutils literal notranslate"><span class="pre">count/{word}</span></code> endpoint of the <code class="docutils literal notranslate"><span class="pre">RetrieveCounts</span></code> service
in the application <code class="docutils literal notranslate"><span class="pre">WordCount</span></code> in the namespace <em>default</em> to get a count of the
word “Cask” and its associated words with a limit of 2.</td>
</tr>
<tr class="row-odd"><th class="stub">Response Status Code</th>
<td><code class="docutils literal notranslate"><span class="pre">200</span> <span class="pre">OK</span></code></td>
</tr>
<tr class="row-even"><th class="stub">Response Body</th>
<td><code class="docutils literal notranslate"><span class="pre">{</span> <span class="pre">&quot;assocs&quot;:</span> <span class="pre">{</span> <span class="pre">&quot;CaskData&quot;:</span> <span class="pre">1,</span> <span class="pre">&quot;CaskInc&quot;:</span> <span class="pre">1</span> <span class="pre">},</span> <span class="pre">&quot;count&quot;:</span> <span class="pre">5,</span> <span class="pre">&quot;word&quot;:</span> <span class="pre">&quot;Cask&quot;}</span></code></td>
</tr>
</tbody>
</table>
</div>
</div>

</div>
    <div class="col-md-2">
      <div id="right-sidebar" class="bs-sidenav scrollable-y" role="complementary">
        <div id="localtoc-scrollspy">
        </div>
      </div>
    </div></div>
</div>
<!-- block main content end -->
<!-- block footer -->
<footer class="footer">
      <div class="container">
        <div class="row">
          <div class="col-md-2 footer-left"><a title="Security HTTP RESTful API" href="security.html" />Previous</a></div>
          <div class="col-md-8 footer-center"><a class="footer-tab-link" href="../table-of-contents/../../reference-manual/licenses/index.html">Copyright</a> &copy; 2014-2020 Cask Data, Inc.&bull; <a class="footer-tab-link" href="//docs.cask.co/cdap/6.1.1/cdap-docs-6.1.1-web.zip" rel="nofollow">Download</a> an archive or
<a class="footer-tab-link" href="//docs.cask.co/cdap">switch the version</a> of the documentation
          </div>
          <div class="col-md-2 footer-right"><a title="Transaction Service HTTP RESTful API" href="transactions.html" />Next</a></div>
        </div>
      </div>
    </footer>
<!-- block footer end -->
<script type="text/javascript" src="../_static/bootstrap-3.3.6/js/bootstrap.min.js"></script><script type="text/javascript" src="../_static/js/bootstrap-sphinx.js"></script><script type="text/javascript" src="../_static/js/abixTreeList-2.js"></script><script type="text/javascript" src="../_static/js/cdap-dynamicscrollspy-4.js"></script><script type="text/javascript" src="../_static/js/cdap-version-menu.js"></script><script type="text/javascript" src="../_static/js/copy-to-clipboard.js"></script><script type="text/javascript" src="../_static/js/jquery.mousewheel.min.js"></script><script type="text/javascript" src="../_static/js/jquery.mCustomScrollbar.js"></script><script type="text/javascript" src="../_static/js/js.cookie.js"></script><script type="text/javascript" src="../_static/js/tabbed-parsed-literal-0.2.js"></script><script type="text/javascript" src="../_static/js/cdap-onload-javascript.js"></script><script type="text/javascript" src="../_static/js/cdap-version-menu.js"></script>
    <script src="https://cdap.gitee.io/docs/cdap/json-versions.js"/></script>
  </body>
</html>